CGAL Editorial Board
This chapter lists the licenses under which the Cgal datastructures and algorithms are distributed. The chapter further explains how to control inlining, thread safety, code deprecation, checking of pre- and postconditions, and how to alter the failure behavior.
Cgal is distributed under a dual license scheme, that is under the Gpl/Lgpl open source license, as well as under commercial licenses.
Cgal consists of different parts covered by different open source licenses. In this section we explain the essence of the different licenses, as well as the rationale why we have chosen them.
The fact that Cgal is Open Source software does not mean that users are free to do whatever they want with the software. Using the software means to accept the license, which has the status of a contract between the user and the owner of the Cgal software.
The Gpl is an Open Source license that, if you distribute your software based on Gpled Cgal data structures,you are obliged to distribute the source code of your software under the Gpl.
The exact license terms can be found at the Free Software Foundation web site: http://www.gnu.org/copyleft/gpl.html.
The Lgpl is an Open Source license that obliges you to distribute modifications you make on Cgal software accessible to the users. In contrast to the Gpl , there is no obligation to make the source code of software you build on top of Lgpled Cgal data structures
The exact license terms can be found at the Free Software Foundation web site: http://www.gnu.org/copyleft/lesser.html.
We have chosen the Gpl and the Lgpl as they are well known and well understood open source licenses. The former restricts commercial use, and the latter allows to promote software as de facto standard so that people can build new higher level data structures on top.
Therefore, the packages forming a foundation layer are distributed under the Lgpl, and the higher level packages under the Gpl. The package overview states for each package under which license it is distributed.
Users who cannot comply to the Open Source license terms can buy individual data structures under various commercial licenses from GeometryFactory: http://www.geometryfactory.com/. License fees paid by commercial customers are reinvested in R&D performed by the Cgal project partners, as well as in evolutive maintenance.
In this manual you will encounter sections marked as follows.
Some functionality is considered more advanced, for example because it is relatively low-level, or requires special care to be properly used.
Usually related to advanced features that for example may not guarantee class invariants, some functionality is provided that helps debugging, for example by performing invariants checks on demand.
Sometimes, the Cgal project decides that a feature is deprecated. This means that it still works in the current release, but it will be removed in the next, or a subsequent release. This can happen when we have found a better way to do something, and we would like to reduce the maintenance cost of Cgal at some point in the future. There is a trade-off between maintaining backward compatibility and implementing new features more easily.
In order to help users manage the changes to apply to their code, we attempt to make Cgal code emit warnings when deprecated code is used. This can be done using some compiler specific features. Those warnings can be disabled by defining the macro CGAL_NO_DEPRECATION_WARNINGS. On top of this, we also provide a macro, CGAL_NO_DEPRECATED_CODE, which, when defined, disables all deprecated features. This allows users to easily test if their code relies on deprecated features.
All names introduced by Cgal, especially those documented in these manuals, are in a namespace called CGAL, which is in global scope. A user can either qualify names from Cgal by adding CGAL::, e.g., CGAL::Point_2< CGAL::Exact_predicates_inexact_constructions_kernel >, make a single name from Cgal visible in a scope via a using statement, e.g., using CGAL::Point_2;, and then use this name unqualified in this scope, or even make all names from namespace CGAL visible in a scope with using namespace CGAL;. The latter, however, is likely to give raise to name conflicts and is therefore not recommended.
Not all compilers fully support standard header names. Cgal provides workarounds for these problems in CGAL/basic.h. Consequently, as a golden rule, you should always include CGAL/basic.h first in your programs (or CGAL/Cartesian.h, or CGAL/Homogeneous.h, since they include CGAL/basic.h first).
Cgal is progressively being made thread-safe. The guidelines which are followed are:
If the macro CGAL_HAS_THREADS is not defined, then Cgal assumes it can use any thread-unsafe code (such as static variables). By default, this macro is not defined, unless BOOST_HAS_THREADS or _OPENMP is defined. It is possible to force its definition on the command line, and it is possible to prevent its default definition by setting CGAL_HAS_NO_THREADS from the command line.
Cgal is based on the C++ standard released in 1998 (and later refined in 2003). A new major version of this standard has been released, and is refered to as C++11. Some compilers and standard library implementations already provide some of the functionality of this new standard. For example, g++ provides a command-line switch (-std=c++0x or -std=c++11 depending on the compiler version) which enables some of those features.
Cgal attempts to support this mode progressively, and already makes use of some of these features if they are available, although no extensive support has been implemented yet.
Cgal functors support the result_of protocol. If a functor F has the same return type across all overloads of operator(), the nested type F::result_type is defined to be that type. Otherwise the return type of calling the functor with an argument of type Arg can be accessed through boost::result_of<F(Arg)>::type.
Much of the Cgal code contains checks. For example, all checks used in the kernel code are prefixed by CGAL_KERNEL. Other packages have their own prefixes, as documented in the corresponding chapters. Some are there to check if the kernel behaves correctly, others are there to check if the user calls kernel routines in an acceptable manner.
There are five types of checks. The first three are errors and lead to a halt of the program if they fail. The fourth only leads to a warning, and the last one is compile-time only.
By default, all of these checks are performed.
It is however possible to turn them off through the use of compile time
switches.
For example, for the checks in the kernel code, these switches are the
following:
CGAL_KERNEL_NO_PRECONDITIONS,
CGAL_KERNEL_NO_POSTCONDITIONS,
CGAL_KERNEL_NO_ASSERTIONS and
CGAL_KERNEL_NO_WARNINGS.
So, in order to compile the file foo.cpp with the postcondition checks
off, you can do:
CC -DCGAL_KERNEL_NO_POSTCONDITIONS foo.cpp
This is also preferably done by modifying your makefile by adding -DCGAL_KERNEL_NO_POSTCONDITIONS to the CXXFLAGS variable.
The name KERNEL in the macro name can be replaced by a package specific name in order to control assertions done in a given package. This name is given in the documentation of the corresponding package, in case it exists.
Note that global macros can also be used to control the behavior over the whole Cgal library:
Setting the macro CGAL_NDEBUG disables all checks. Note that the standard flag NDEBUG sets CGAL_NDEBUG, but it also affects the standard assert macro. This way, adding -DCGAL_NDEBUG to your compilation flags removes absolutely all checks. This is the default recommended setup for performing timing benchmarks for example.
Not all checks are on by default. The first four types of checks can be marked as expensive or exactness checks (or both). These checks need to be turned on explicitly by supplying one or both of the compile time switches CGAL_KERNEL_CHECK_EXPENSIVE and CGAL_KERNEL_CHECK_EXACTNESS.
Expensive checks are, as the word says, checks that take a considerable time to compute. Considerable is an imprecise phrase. Checks that add less than 10 percent to the execution time of the routine they are in are not expensive. Checks that can double the execution time are. Somewhere in between lies the border line. Checks that increase the asymptotic running time of an algorithm are always considered expensive. Exactness checks are checks that rely on exact arithmetic. For example, if the intersection of two lines is computed, the postcondition of this routine may state that the intersection point lies on both lines. However, if the computation is done with doubles as number type, this may not be the case, due to round off errors. So, exactness checks should only be turned on if the computation is done with some exact number type.
By definition, static assertions are both inexpensive and unaffected by precision management. Thus, the categories do not apply for static assertions.
As stated above, if a postcondition, precondition or assertion is violated, an exception is thrown, and if nothing is done to catch it, the program will abort. This behavior can be changed by means of the following function.
#include <CGAL/assertions_behaviour.h>
| Failure_behaviour | set_error_behaviour ( Failure_behaviour eb) | |
The parameter should have one of the following values.
| enum Failure_behaviour { ABORT, EXIT, EXIT_WITH_SUCCESS, CONTINUE, THROW_EXCEPTION}; |
If the EXIT value is set, the program will stop and return a value indicating failure, but not dump the core. The CONTINUE value tells the checks to go on after diagnosing the error. Note that since Cgal 3.4, CONTINUE has the same effect as THROW_EXCEPTION for errors (but it keeps its meaning for warnings), it is not possible anymore to let assertion failures simply continue (except by totally disabling them).
The value that is returned by set_error_behaviour is the value that was in use before.
For warnings there is a separate routine, which works in the same way. The only difference is that for warnings the default value is CONTINUE.
| Failure_behaviour | set_warning_behaviour ( Failure_behaviour eb) | |
The compile time flags as described up to now all operate on the whole library. Sometimes you may want to have a finer control. Cgal offers the possibility to turn checks on and off with a bit finer granularity, namely the module in which the routines are defined. The name of the module is to be appended directly after the Cgal prefix. So, the flag CGAL_KERNEL_NO_ASSERTIONS switches off assertions in the kernel only, the flag CGAL_CH_CHECK_EXPENSIVE turns on expensive checks in the convex hull module. The name of a particular module is documented with that module.
Normally, error messages are written to the standard error output. It is possible to do something different with them. To that end you can register your own handler. This function should be declared as follows.
| void |
| |||||
Your failure function will be called with the following parameters. type is a string that contains one of the words precondition, postcondition, assertion or warning. The parameter expression contains the expression that was violated. file and line contain the place where the check was made. The explanation parameter contains an explanation of what was checked. It can be NULL, in which case the expression is thought to be descriptive enough.
There are several things that you can do with your own handler. You can display a diagnostic message in a different way, for instance in a pop up window or to a log file (or a combination). You can also implement a different policy on what to do after an error. For instance, you can throw an exception or ask the user in a dialog whether to abort or to continue. If you do this, it is best to set the error behavior to CONTINUE, so that it does not interfere with your policy.
You can register two handlers, one for warnings and one for errors. Of course, you can use the same function for both if you want. When you set a handler, the previous handler is returned, so you can restore it if you want.
#include <CGAL/assertions.h>
| Failure_function | set_error_handler ( Failure_function handler) | |
| Failure_function | set_warning_handler ( Failure_function handler) | |
#include <CGAL/assertions.h>
void my_failure_handler(
const char *type,
const char *expr,
const char* file,
int line,
const char* msg)
{
/* report the error in some way. */
}
void foo()
{
CGAL::Failure_function prev;
prev = CGAL::set_error_handler(my_failure_handler);
/* call some routines. */
CGAL::set_error_handler(prev);
}
#include <CGAL/config.h>
Every release of Cgal defines the following preprocessor macros:
More precisely, it is defined as 1MMmmbiiii, where MM is the major release number (e.g. 03), mm is the minor release number (e.g. 02), b is the bug-fix release number (e.g. 0), and iiii is the internal release number (e.g. 0001). For public releases, the latter is defined as 1000. Examples: for the public release 3.2.4 this number is 1030241000; for internal release 3.2-I-1, it is 1030200001. Note that this scheme was modified around 3.2-I-30.
Making functions inlined can, at times, improve the efficiency of your code. However this is not always the case and it can differ for a single function depending on the application in which it is used. Thus Cgal defines a set of compile-time macros that can be used to control whether certain functions are designated as inlined functions or not. The following table lists the macros and their default values, which are set in one of the Cgal include files.
| macro name | default |
| CGAL_KERNEL_INLINE | inline |
| CGAL_KERNEL_MEDIUM_INLINE | |
| CGAL_KERNEL_LARGE_INLINE | |
| CGAL_MEDIUM_INLINE | inline |
| CGAL_LARGE_INLINE | |
| CGAL_HUGE_INLINE | |
If you wish to change the value of one or more of these macros, you can simply give it a new value when compiling. For example, to make functions that use the macro CGAL_KERNEL_MEDIUM_INLINE inline functions, you should set the value of this macro to inline instead of the default blank.
Note that setting inline manually is very fragile, especially in a template context. It is usually better to let the compiler select by himself which functions should be inlined or not.